<html>
  <head>
    <title>Ratings</title>
  </head>
  <body bgcolor="#ffffff" text="#000000">
    <font face="Verdana,Arial,Helvetica" SIZE="2">
      <center><b>Ratings</b></center>
    <br />
    <br />

    <h1>Introduction</h1>

    The ratings module allows any module developer to add ratings to their
    module items with ease.  This module is not designed to be called directly,
    but instead is meant to be called as a utility module from within other
    modules to expand their functionality.

    <h1>API</h1>

    The API for the ratings module consists of the following user functions

    <h2>display</h2>

    <i>display</i> provides a suitable output string for displaying the current
    rating of a defined item.  The variables used by this function are as
    follows:

    <ul>
      <li />
      <b>modname</b> - the name of the module to get the rating for
      <li />
      <b>itemid</b> - the item in the module to get the rating for
      <li />
      <b>ratingtype</b> - the type of the rating (optional)
      <li />
      <b>style</b> - the style in which to display the rating (optional).
      The style can be one of the following items:
      <ul>
        <li />
        <i>percentage</i> - rating shown as a percentage
        <li />
        <i>outoffive</i> - rating shown as value out of five
        <li />
        <i>outoffivestars</i> - rating shown as value out of five using stars
        <li />
        <i>outoften</i> - rating shown as value out of ten
        <li />
        <i>outoftenstars</i> - rating shown as value out of ten using stars
      </ul>
    </ul>
    <p />

    This function returns a suitable output string if the rating is known to
    the system, or <i>void</i> if it is not.

    <h2>ask</h2>

    <i>ask</i> provides a suitable output string to ask for a rating of a
    defined item.  The variables used by this function are as follows:

    <ul>
      <li />
      <b>modname</b> - the name of the module to obtain a rating for
      <li />
      <b>itemid</b> - the item in the module to obtain a rating for
      <li />
      <b>ratingtype</b> - the type of the rating (optional)
      <li />
      <b>returnurl</b> - the URL to return to after the ratings has been
      obtained
      <li />
      <b>style</b> - the style in which to obtain a rating (optional).  See
      above for details
    </ul>
    <p />

    This function returns a suitable output string if the current user is
    allowed to rate the item, or <i>void</i> if they are not.

    <h1>Examples</h1>

    The example below shows how to use the functions provided with this API.
    The example is used with the 'News' module and
    uses the <i>sid</i> variable as the rating item id.

    <pre font="fixed">
      // Show rating for news item
      if (pnModLoad('Ratings')) {
          $rating = pnModFunc('Ratings',
                              'user',
                              'display',
                              array('modname' =&gt; 'News',
                                    'itemid' =&gt; $sid));
          if (isset($rating)) {
              $output-&gt;Text('Rating for this story: ');
              $output-&gt;SetInputState(_PNH_VERBATIMINPUT);
              $output-&gt;Text($rating);
              $output-&gt;SetInputState(_PNH_PARSEINPUT);
          }

          $askrating = pnModFunc('Ratings',
                                 'user',
                                 'ask',
                                 array('modname' =&gt; 'News',
                                       'itemid' =&gt; $sid,
                                       'returnurl' =&gt; pnModURL('News',
                                                               'user',
                                                               'display',
                                                               array('sid' =&gt; $sid))));
          $output-&gt;SetInputState(_PNH_VERBATIMINPUT);
          $output-&gt;Text($askrating);
          $output-&gt;SetInputState(_PNH_PARSEINPUT);
      }
    </pre>


    <h1>Permission</h1>

    The permissions for the ratings module are as follows:

     <h2>Component</h2>

     The component is simply 'Ratings::'

     <h2>Instance</h2>

     The instance is 'Module name:Rating type:Item ID'.  The items are
     described below:

     <ul>
       <li />
       <b>Module name</b> - the module name as passed in as <i>modname</i> to
       the <i>display</i> and <i>ask</i> functions as above
       <li />
       <b>Rating type</b> - the specific type of rating that this item is for,
       as passed in as <i>ratingtype</i> to the <i>display</i> and <i>ask</i>
       functions as above.  If no value is supplied this is set to 'default'
       <li />
       <b>Item ID</b> - the module-specific ID of the item being rated, as
       passed in as <i>itemid</i> to the <i>display</i> and <i>ask</i>
       functions as above.
     </ul>
     <p />

     A user needs to have at least read permission to see an item's rating, and
     at least comments permission to be able to rate an item.

     <h1>Configuration</h1>

     The module has two configuration variables, described below.

     <h2>defaultstyle</h2>

     This variable specifies the style in which ratings are displayed when no
     specific display style is supplied by the calling module.  This variable
     can take the value of any of the display styles available, as listed
     above.

     <h2>seclevel</h2>

     This variables specificies the security level that is applied to ratings
     in an attempt to avoid users being able to rig ratings.  The higher the
     security level the harder it is for a user to be able to rate an item
     multiple times, but the more work that Zikula has to do to try to ensure
     that the user is not attempting to rate a single item many times.

  </body>
</html>
